DateNN 2   IE J1   ECMA 1

The Date object is a static object that generates instances by way of several constructor functions. Each instance of a Date object is a snapshot of the date and time, measured in milliseconds relative to zero hours on January 1, 1970. Negative millisecond values represent time before that date; positive values represent time since that date.

The typical way to work with dates is to generate a new Date object instance, either for now or for a specific date and time (past or future, using the client local time). Then use the myriad of available date methods to get or set components of that time (e.g., minutes, hours, date, month). Browsers internally store a date as the millisecond value at Coordinated Universal Time (UTC, which is essentially the same as Greenwich Mean Time, or GMT). When you ask a browser for a component of that time, it automatically converts the value to the local time zone of the browser based on the client computer's control panel setting for the clock and time zone. If the control panel is set incorrectly, time and date calculations may go awry.

Early versions of scriptable browsers had numerous bugs when working with the Date object. One resource that explains the ins and outs of working with the Date object (and bugs) can be found at http://developer.netscape.com/viewsource/goodman_dateobject.html.

 
Creating a Date Object
var now = new Date()
var myDate = new Date("month dd, yyyy hh:mm:ss")
var myDate = new Date("month dd, yyyy")
var myDate = new Date(yy, mm, dd, hh, mm, ss)
var myDate = new Date(yy, mm, dd)
var myDate = new Date(milliseconds)
prototypeNN 3   IE J2   ECMA 1
 Read/Write
 

A property of the static Date object. Use the prototype property to assign new properties and methods to future instances of a Date value created in the current document. See the Array.prototype property description for examples.

 
Example
Date.prototype.author = "DG"
 
Value
Any data, including function references.
getDate()NN 2   IE J1   ECMA 1

Returns the date within the month specified by the Date object.

 
Returned Value
Integer between 1 and 31.
 
Parameters
None.
getDay()NN 2   IE J1   ECMA 1

Returns an integer corresponding to a day of the week for the date specified by the Date object.

 
Returned Value
Integer between 0 and 6. Sunday is 0, Monday is 1, and Saturday is 6.
 
Parameters
None.
getFullYear()NN 4   IE J3   ECMA 1

Returns all digits of the year for the date specified by the Date object.

 
Returned Value
Integer. Navigator goes no lower than zero. Internet Explorer returns negative year values.
 
Parameters
None.
getHours()NN 2   IE J1   ECMA 1

Returns a zero-based integer corresponding to the hours of the day for the date specified by the Date object. The 24-hour time system is used.

 
Returned Value
Integer between 0 and 23.
 
Parameters
None.
getMilliseconds()NN 4   IE J3   ECMA 1

Returns a zero-based integer corresponding to the number of milliseconds past the seconds value of the date specified by the Date object.

 
Returned Value
Integer between 0 and 999.
 
Parameters
None.
getMinutes()NN 2   IE J1   ECMA 1

Returns a zero-based integer corresponding to the minute value for the hour and date specified by the Date object.

 
Returned Value
Integer between 0 and 59.
 
Parameters
None.
getMonth()NN 2   IE J1   ECMA 1

Returns a zero-based integer corresponding to the month value for the date specified by the Date object. That this method's values are zero-based frequently confuses scripters at first.

 
Returned Value
Integer between and 11. January is 0, February is 1, and December is 11.
 
Parameters
None.
getSeconds()NN 2   IE J1   ECMA 1

Returns a zero-based integer corresponding to the seconds past the nearest full minute for the date specified by the Date object.

 
Returned Value
Integer between 0 and 59.
 
Parameters
None.
getTime()NN 2   IE J1   ECMA 1

Returns a zero-based integer corresponding to the number of milliseconds since January 1, 1970, to the date specified by the Date object.

 
Returned Value
Integer.
 
Parameters
None.
getTimezoneOffset()NN 2   IE J1   ECMA 1

Returns a zero-based integer corresponding to the number of minutes difference between GMT and the client computer's clock. Time zones to the west of GMT are positive values; time zones to the east are negative values. Numerous bugs plagued this method in earlier browsers, especially Macintosh versions.

 
Returned Value
Integer between -720 and 720.
 
Parameters
None.
getUTCDate()NN 4   IE J3   ECMA 1

Returns the date within the month specified by the Date object but in the UTC time stored internally by the browser.

 
Returned Value
Integer between 1 and 31.
 
Parameters
None.
getUTCDay()NN 4   IE J3   ECMA 1

Returns an integer corresponding to a day of the week for the date specified by the Date object but in the UTC time stored internally by the browser.

 
Returned Value
Integer between 0 and 6. Sunday is 0, Monday is 1, and Saturday is 6.
 
Parameters
None.
getUTCFullYear()NN 4   IE J3   ECMA 1

Returns all digits of the year for the date specified by the Date object but in the UTC time stored internally by the browser.

 
Returned Value
Integer. Navigator goes no lower than zero. Internet Explorer returns negative year values.
 
Parameters
None.
getUTCHours()NN 4   IE J3   ECMA 1

Returns a zero-based integer corresponding to the hours of the day for the date specified by the Date object but in the UTC time stored internally by the browser. The 24-hour time system is used.

 
Returned Value
Integer between 0 and 23.
 
Parameters
None.
getUTCMilliseconds()NN 4   IE J3   ECMA 1

Returns a zero-based integer corresponding to the number of milliseconds past the seconds value of the date specified by the Date object but in the UTC time stored internally by the browser.

 
Returned Value
Integer between 0 and 999.
 
Parameters
None.
getUTCMinutes()NN 4   IE J3   ECMA 1

Returns a zero-based integer corresponding to the minute value for the hour and date specified by the Date object but in the UTC time stored internally by the browser.

 
Returned Value
Integer between 0 and 59.
 
Parameters
None.
getUTCMonth()NN 4   IE J3   ECMA 1

Returns a zero-based integer corresponding to the month value for the date specified by the Date object but in the UTC time stored internally by the browser. That this method's values are zero-based frequently confuses scripters at first.

 
Returned Value
Integer between and 11. January is 0, February is 1, and December is 11.
 
Parameters
None.
getUTCSeconds()NN 4   IE J3   ECMA 1

Returns a zero-based integer corresponding to the seconds value past the nearest full minute of the date specified by the Date object but in the UTC time stored internally by the browser.

 
Returned Value
Integer between 0 and 59.
 
Parameters
None.
getYear()NN 2   IE J1   ECMA 1

Returns a number corresponding to the year but exhibits irregular behavior. In theory, the method should return the number of years the date object represents since 1900. This would produce a one- or two-digit value for all years between 1900 and 1999. However when you reach 2000, the pattern fails. Instead of producing values starting with 100, the getYear() method starting with Navigator 3 and IE 4, returns the same four-digit value as getFullYear(). For this reason, it is best to use getFullYear() whenever possible (but observe the browser compatibility for that method).

 
Returned Value
Integer between and 99 for the years 1900 to 1999; four-digit integer starting with 2000.
 
Parameters
None.
parse()NN 2   IE J1   ECMA 1
parse(dateString) 
 

Static method that returns the millisecond equivalent of the date specified as a string in the parameter.

 
Returned Value
Date in milliseconds.
 
Parameters
dateString Any valid string format equivalent to that derived from a Date object. See toString(), toGMTString(), and toLocaleString() methods for sample formats.
setDate()NN 2   IE J1   ECMA 1
setDate(dateInt) 
 

Sets the date within the month specified by the Date object. This method alters the value of the instance of the Date object.

 
Returned Value
New date in milliseconds.
 
Parameters
dateInt Integer between 1 and 31.
setFullYear()NN 4   IE J3   ECMA 1
setFullYear(yearInt) 
 

Assigns the year for the date specified by the Date object. This method alters the value of the instance of the Date object.

 
Returned Value
New date in milliseconds.
 
Parameters
yearInt Integer. Navigator allows digits no lower than zero. Internet Explorer allows negative year values.
setHours()NN 2   IE J1   ECMA 1
setHours(hourInt) 
 

Sets the hours of the day for the date specified by the Date object. The 24-hour time system is used. This method alters the value of the instance of the Date object.

 
Returned Value
New date in milliseconds.
 
Parameters
hourInt Integer between 0 and 23.
setMilliseconds()NN 4   IE J3   ECMA 1
setMilliseconds(msInt) 
 

Sets the number of milliseconds past the seconds value of the date specified by the Date object. This method alters the value of the instance of the Date object.

 
Returned Value
New date in milliseconds.
 
Parameters
msInt Integer between 0 and 999.
setMinutes()NN 2   IE J1   ECMA 1
setMinutes(minuteInt) 
 

Sets the minute value for the hour and date specified by the Date object. This method alters the value of the instance of the Date object.

 
Returned Value
New date in milliseconds.
 
Parameters
minuteInt Integer between 0 and 59.
setMonth()NN 2   IE J1   ECMA 1
setMonth(monthInt) 
 

Sets the month value for the date specified by the Date object. That this method's values are zero-based frequently confuses scripters at first. This method alters the value of the instance of the Date object.

 
Returned Value
New date in milliseconds.
 
Parameters
monthInt Integer between and 11. January is 0, February is 1, and December is 11.
setSeconds()NN 2   IE J1   ECMA 1
setSeconds(secInt) 
 

Sets the seconds value past the nearest full minute of the date specified by the Date object. This method alters the value of the instance of the Date object.

 
Returned Value
New date in milliseconds.
 
Parameters
secInt Integer between 0 and 59.
setTime()NN 2   IE J1   ECMA 1
setTime(msInt) 
 

Sets the Date object to the number of milliseconds since January 1, 1970. This method alters the value of the instance of the Date object.

 
Returned Value
New date in milliseconds.
 
Parameters
msInt Integer.
setUTCDate()NN 4   IE J3   ECMA 1
setUTCDate(dateInt) 
 

Sets the date within the month specified by the Date object but in the UTC time stored internally by the browser.

 
Returned Value
New UTC date in milliseconds.
 
Parameters
dateInt Integer between 1 and 31.
setUTCFullYear()NN 4   IE J3   ECMA 1
setUTCFullYear(yearInt) 
 

Sets all digits of the year for the date specified by the Date object but in the UTC time stored internally by the browser. This method alters the value of the instance of the Date object.

 
Returned Value
New UTC date in milliseconds.
 
Parameters
yearInt Integer. Navigator allows values no lower than zero. Internet Explorer allows negative year values.
setUTCHours()NN 4   IE J3   ECMA 1
setUTCHours(hourInt) 
 

Sets the hours of the day for the date specified by the Date object but in the UTC time stored internally by the browser. The 24-hour time system is used. This method alters the value of the instance of the Date object.

 
Returned Value
New UTC date in milliseconds.
 
Parameters
hourInt Integer between 0 and 23.
setUTCMilliseconds()NN 4   IE J3   ECMA 1
setUTCMilliseconds(msInt) 
 

Sets the number of milliseconds past the seconds value of the date specified by the Date object but in the UTC time stored internally by the browser. This method alters the value of the instance of the Date object.

 
Returned Value
New UTC date in milliseconds.
 
Parameters
msInt Integer between 0 and 999.
setUTCMinutes()NN 4   IE J3   ECMA 1
setUTCMinutes(minuteInt) 
 

Sets the minute value for the hour and date specified by the Date object but in the UTC time stored internally by the browser. This method alters the value of the instance of the Date object.

 
Returned Value
New UTC date in milliseconds.
 
Parameters
minuteInt Integer between 0 and 59.
setUTCMonth()NN 4   IE J3   ECMA 1
setUTCMonth(monthInt) 
 

Sets the month value for the date specified by the Date object but in the UTC time stored internally by the browser. That this method's values are zero-based frequently confuses scripters at first. This method alters the value of the instance of the Date object.

 
Returned Value
New UTC date in milliseconds.
 
Parameters
monthInt Integer between and 11. January is 0, February is 1, and December is 11.
setUTCSeconds()NN 4   IE J3   ECMA 1
setUTCSeconds(secInt) 
 

Sets the seconds value past the nearest full minute specified by the Date object but in the UTC time stored internally by the browser.

 
Returned Value
New UTC date in milliseconds.
 
Parameters
secInt Integer between 0 and 59.
setYear()NN 2   IE J1   ECMA 1
setYear(yearInt) 
 

Sets the year of a Date object. Use setFullYear() if the browser versions you support allow it.

 
Returned Value
New date in milliseconds.
 
Parameters
yearInt Integer between and 99 for the years 1900 to 1999; four-digit integer starting with 2000. Four-digit integers also accepted for years before 2000.
toGMTString()NN 2   IE J1   ECMA 1

Returns a string version of the GMT value of a Date object instance in a standardized format. This method does not alter the original Date object. For use in newer browsers, the toUTCString() method is recommended in favor of toGMTString().

 
Returned Value
String in the following format: dayAbbrev, dd mmm yyyy hh:mm:ss GMT. For example:
Wed 05 Aug 1998 02:33:22 GMT
 
Parameters
None.
toLocaleString()NN 2   IE J1   ECMA 1

Returns a string version of the local time zone value of a Date object instance in a format that may be localized for a particular country or an operating system's convention. This method does not alter the original Date object.

 
Returned Value
String in a variety of possible formats. Examples of U.S. versions of browsers include:

Platform

String Value

Navigator 4/Win32

03/31/98 11:22:44

Navigator 4/MacPPC

Mar 31 11:22:44 1998

Internet Explorer 4/Win32

03/31/98 11:22:44

Internet Explorer 4/MacPPC

Tuesday, 31 March, 1998 11:22:44 AM
 
Parameters
None.
toString()NN 2   IE J2   ECMA 1

A static method used mostly by the browser itself to convert Date objects to string values when needed for display in dialog boxes or on-screen rendering. This method is inherited by Date object instances, so you may use it to script string conversion if the other available formats are not to your liking.

 
Returned Value
String in a variety of possible formats. Examples of U.S. versions of browsers include:

Platform

String Value

Navigator 4/Win32

Tue Mar 31 11:22:04 Pacific Standard Time 1998

Navigator 4/MacPPC

Tue Mar 31 11:30:24 1998

Internet Explorer 4/Win32

Tue Mar 31 11:22:04 PST 1998

Internet Explorer 4/MacPPC

Tue Mar 31 11:30:24 PST 1998
 
Parameters
None.
toUTCString()NN 4   IE J3   ECMA 1

Returns a string version of the UTC value of a Date object instance in a standardized format. This method does not alter the original Date object. For use in newer browsers, the toUTCString() method is recommended in favor of toGMTString().

 
Returned Value
String in the following format: dayAbbrev, dd mmm yyyy hh:mm:ss GMT. For example:
Wed 05 Aug 1998 02:33:22 GMT
 
Parameters
None.
UTC()NN 2   IE J1   ECMA 1
UTC(yyyy, mm, dd[, hh[, mm[, ss[, msecs]]]])  
 

A static method of the Date object that returns a numeric version of the date as stored internally by the browser for a Date object. Unlike parameters to the Date object constructor, the parameter values for the UTC() method must be in UTC time for the returned value to be accurate. This method does not generate a date object, as the Date object constructor does.

 
Returned Value
Integer of the UTC millisecond value of the date specified as parameters.
 
Parameters
yyyy Four-digit year value.
mm Two-digit month number (0-11).
dd Two-digit date number (1-31).
hh Optional two-digit hour number in 24-hour time (0-23).
mm Optional two-digit minute number (0-59).
ss Optional two-digit second number (0-59).
msec Optional milliseconds past the last whole second (0-999).
valueOf()NN 4   IE J3   ECMA 1

Returns the object's value.

 
Returned Value
Integer millisecond count.
 
Parameters
None.